Node / mirrors / RTNode-HeltecV4 / files / README.md

Displaying Rendered • View raw • Download

A custom firmware for the Heltec WiFi LoRa 32 V4 (ESP32-S3 + SX1262) that operates as a Boundary Node — bridging a local LoRa radio network with a remote TCP/IP backbone (such as rmap.world) over WiFi.

T282828

Built on microReticulum (a C++ port of the Reticulum network stack) and the RNode firmware by Mark Qvist.

• Bidirectional LoRa ↔ TCP bridging — local LoRa mesh nodes can reach the global Reticulum backbone and vice versa

• Web-based configuration portal — WiFi SSID/password, backbone host/port, LoRa parameters, all configurable via captive portal

• OLED status display — real-time status indicators for LoRa, WiFi, WAN (backbone), LAN (local TCP), plus IP address, port, and airtime

• Optional local TCP server — serve local devices on your WiFi in addition to the backbone connection

• Automatic reconnection — WiFi and TCP connections recover from drops with exponential backoff

• ESP32 memory-optimized — table sizes, timeouts, and caching tuned for the constrained MCU environment

The Heltec WiFi LoRa 32 V4 was chosen because it ships standard with 2 MB PSRAM and 16 MB flash — enough headroom for the microReticulum transport tables, packet caching to flash storage, and the web-based configuration portal. Many other LoRa dev boards come with only 4–8 MB flash and no PSRAM, which would require significant compromises to the boundary node's caching and routing capabilities.

The easiest way to flash a pre-built firmware. You only need Python 3 and a USB cable.

T282828

pip install esptool

T8b949e# Clone this repo (or download just flash.py + the firmware binary)

git clone https://github.com/jrl290/RNodeTHV4.git

Tffa657cd RNodeTHV4

T8b949e# Download latest firmware from GitHub Releases and flash

python flash.py --download

T8b949e# Or flash a local binary

python flash.py --file rnodethv4_firmware.bin

The flash utility will list all available serial ports and prompt you to choose one. If no ports are detected, you may need to hold the BOOT button while pressing RESET to enter download mode.

For development or customization:

T282828

git clone https://github.com/jrl290/RNodeTHV4.git

Tffa657cd RNodeTHV4

T8b949e# Build

pio run -e heltec_V4_boundary

T8b949e# Flash (via PlatformIO)

pio run -e heltec_V4_boundary -t upload

T8b949e# Or create a merged binary and flash with the utility

python flash.py --merge-only T8b949e# creates rnodethv4_firmware.bin

python flash.py T8b949e# flash it

T8b949e# Monitor serial output (optional)

pio device monitor -e heltec_V4_boundary

If you have the merged binary (T383838rnodethv4_firmware.bin), you can flash it with a single esptool command:

T282828

esptool.py --chip esp32s3 --port /dev/ttyACM0 --baud T79c0ff921600 Tffea00\

write_flash -z --flash_mode qio --flash_freq 80m --flash_size 16MB Tffea00\

0x0 rnodethv4_firmware.bin

Replace T383838/dev/ttyACM0 with your serial port (T383838/dev/cu.usbmodem* on macOS, T383838COM3 on Windows).

On first boot (or if no configuration is found), the device automatically enters the Configuration Portal.

The config portal activates automatically on:

• First boot — when no saved configuration exists

• Button hold >5 seconds — hold the PRG button for 5+ seconds, the device reboots into config mode

When active, the device creates a WiFi access point named T383838RNode-Boundary-Setup (open network). A captive portal should appear automatically when you connect; if not, browse to T383838http://192.168.4.1.

The web form has four sections:

After saving, the device reboots with the new configuration applied.

The 128×64 OLED is split into two panels:

T282828

• Filled circle (●) = active/connected

• Unfilled circle (○) = inactive/disconnected

• Labels are UPPERCASE when active, lowercase when inactive (except LAN which is always uppercase)

• LAN row is hidden when the Local TCP Server is disabled in configuration — the remaining layout stays in place

T282828

• Port shows the Local TCP server port (the port local nodes connect to), not the backbone port

• Port line is hidden when the Local TCP Server is disabled

The firmware runs up to three RNS interfaces simultaneously, using different interface modes to control announce propagation and routing behavior:

The LoRa radio operates in Access Point mode. In Reticulum, this means:

• The interface broadcasts its own announces but blocks rebroadcast of remote announces from crossing to LoRa

• This prevents backbone announces (hundreds of remote destinations) from flooding the limited-bandwidth LoRa channel

• Local nodes discover the boundary node directly; the boundary node answers path requests for remote destinations from its cache

The TCP backbone connection uses T383838MODE_BOUNDARY (T3838380x20), a custom implementation of the Reticulum boundary concept adapted for the memory-constrained ESP32 environment. In this implementation, boundary mode means:

• Incoming announces from the backbone are received and cached, but not stored in the path table by default — only stored when specifically requested via a path request from a local LoRa node

• This prevents the path table (limited to 48 entries on ESP32) from being overwhelmed by thousands of backbone destinations

• When the path table needs to be culled, boundary-mode paths are evicted first, preserving locally-needed LoRa paths

If enabled, a TCP server on the WiFi network allows local Reticulum nodes to connect. It also uses Access Point mode, with the same announce filtering as LoRa.

• Each TCP interface must have a unique name to produce a unique interface hash — the backbone uses T383838"TcpInterface" and the local server uses T383838"LocalTcpInterface". Without distinct names, both interfaces produce the same hash, causing the interface map lookup to fail when routing packets.

• TCP interfaces are configured with a 10 Mbps bitrate, which causes Reticulum's Transport to prefer TCP paths over LoRa paths (typically ~1–10 kbps) when both are available for the same destination.

• When the Local TCP Server is disabled, its status indicator (LAN) and port number are hidden from the OLED display.

The ESP32-S3 has limited RAM compared to a desktop Reticulum node. Several customizations were made to the microReticulum library to operate reliably within these constraints:

The most critical optimization: backbone announces are not stored in the path table by default. A backbone like T383838rmap.world may advertise hundreds of destinations. Storing them all would evict every local LoRa path.

Instead:

1. Backbone announces are received and their packets cached to flash storage

2. When a local LoRa node requests a path, the boundary checks its cache and responds directly

3. Only specifically requested paths get a path table entry

4. Path table culling prioritizes evicting backbone entries over local ones

When a transport-addressed packet arrives from LoRa but the boundary has no path table entry for it, the firmware:

1. Strips the transport headers (converts T383838HEADER_2 → T383838HEADER_1/BROADCAST)

2. Forwards the raw packet to the backbone interface

3. Creates reverse-table entries so proofs can route back to the sender

This acts as a default route — any packet the boundary can't route locally gets forwarded to the backbone.

The original microReticulum T383838get_cached_packet() function called T383838update_hash() after deserializing cached packets from flash. However, T383838update_hash() only computes the packet hash — it does not parse the raw bytes into fields like T383838destination_hash, T383838data, T383838flags, etc.

This was changed to call T383838unpack() instead, which parses all packet fields AND computes the hash. Without this fix, path responses contained empty destination hashes and were silently dropped by LoRa nodes.

│ Note: T383838unpack() only parses the plaintext routing envelope (destination hash, flags, hops,

│ transport headers). It does not decrypt the end-to-end encrypted payload. Every Reticulum

│ transport node performs equivalent header parsing during normal routing — this is standard

│ behavior, not a security concern.

The C++ T383838std::map::insert() method silently does nothing when a key already exists — unlike Python's T383838dict[key] = value which replaces. The original microReticulum code used T383838insert() to update path table entries, meaning stale LoRa paths were never replaced by newer TCP paths (or vice versa).

This was fixed by calling T383838erase() before T383838insert(), ensuring updated path entries always replace stale ones. Without this fix, the boundary node would continue routing packets via an old interface even after a better path was learned.

Each RNS interface must have a unique name because the name is hashed to produce the interface identifier used in path table lookups. If two interfaces share the same name, they produce the same hash, and T383838std::map can only store one — causing the Transport layer to fail to resolve the correct outbound interface for packets.

The TcpInterface constructor accepts an explicit T383838name parameter: the backbone uses T383838"TcpInterface" and the local server uses T383838"LocalTcpInterface".

In the configuration portal:

1. Set WiFi SSID and password

2. Set TCP Backbone Mode to Client

3. Set Backbone Host to T383838rmap.world

4. Set Backbone Port to T3838384242

5. Save and reboot

On your server, configure T383838rnsd with a TCP Server Interface in T383838~/.reticulum/config:

T282828

Tff7b72[[TCP Server Interface]]

Te6edf3type Tff7b72= Ta5d6ffTCPServerInterface

Te6edf3listen_host Tff7b72= Ta5d6ff0.0.0.0

Te6edf3listen_port Tff7b72= Ta5d6ff4242

Then configure the boundary node as a Client pointing to your server's IP.

On your server, configure T383838rnsd with a TCP Client Interface:

T282828

Tff7b72[[TCP Client to Boundary]]

Te6edf3type Tff7b72= Ta5d6ffTCPClientInterface

Te6edf3target_host Tff7b72= Ta5d6ff<boundary-node-ip>

Te6edf3target_port Tff7b72= Ta5d6ff4242

Set the boundary node's Local TCP Server to Enabled (port 4242).

The firmware depends on microReticulum T3838380.2.4, automatically fetched by PlatformIO on first build. After the first build, the library sources under T383838.pio/libdeps/heltec_V4_boundary/microReticulum/src/ need the patches described in "Routing & Memory Customizations" above. Key files modified:

This project is licensed under the GNU General Public License v3.0 — see LICENSE for details.

Based on:

• RNode Firmware by Mark Qvist (GPL-3.0)

• microReticulum by Chris Attermann (GPL-3.0)

• Reticulum by Mark Qvist (MIT)